home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / sound / vdigit.zip / VPMOD.DOC < prev    next >
Text File  |  1989-06-24  |  6KB  |  172 lines
  1. ------------------------------------------------------------------------------
  2.  
  3. Initialization routine
  4. ----------------------
  5.  
  6. Declaration:
  7.  
  8. short pascal far PVOICE_INIT(void)
  9.  
  10.  
  11. This must be called once before any of the other routines are called. It hooks
  12. the interrupt service routine into the timer tick interrupt vector.
  13.  
  14.  
  15. Return value        Meaning
  16. ------------        -------
  17.      0              success
  18.      1              voice package already initialized
  19.      2              wrong CPU, won't run on 8088 or 8086
  20.  
  21. NOTE:  PVOICE_INIT installs a Control-Break (Int 23h) handler which makes sure
  22.        that the 8253 timer chip and the timer tick vector are restored to
  23.        their original state before program termination. If your program
  24.        installs its own Int 23h handler, then (a) It should be done after
  25.        the call to PVOICE_INIT, and (b) It must call PVOICE_CBREAK before it
  26.        allows the program to terminate. Failure to do this will result in
  27.        a system crash.
  28.  
  29.  
  30. ------------------------------------------------------------------------------
  31.  
  32. Cleanup routine
  33. ---------------
  34.  
  35. Declaration:
  36.  
  37. short pascal far PVOICE_CLEANUP(void)
  38.  
  39.  
  40. This restores the timer tick interrupt vector to its previous state. This
  41. routine must be called before the main program exits to DOS, unless the main
  42. program is memory-resident.
  43.  
  44.  
  45. Return value        Meaning
  46. ------------        -------
  47.      0              success
  48.      1              voice package was not in the initialized state
  49.  
  50.  
  51. ------------------------------------------------------------------------------
  52.  
  53. Start routine
  54. -------------
  55.  
  56. Declaration:
  57.  
  58. short pascal far PVOICE_START(blockaddr,blocklen,
  59.                               fileread,handle,datalen,startpos)
  60. unsigned char far *blockaddr;
  61. long blocklen;
  62. unsigned short fileread;
  63. unsigned short handle;
  64. long datalen;
  65. long startpos;
  66.  
  67.  
  68. This call initiates a voice output operation. It returns to the caller
  69. immediately. Voice output will continue asynchronously (background).
  70.  
  71.  
  72. Parameter   Size   Description
  73. ---------   ----   -----------
  74. blockaddr     4    A far pointer to the memory block used for voice data.
  75. blocklen      4    A dword indicating the length of the memory block.
  76. fileread      2    A flag word. If this is 1, then data will be read from
  77.                     a file. If it is 0, then the data is assumed to be
  78.                     already present in the memory block.
  79. handle        2    An open file handle. This is ignored if the flag word
  80.                     is 0.
  81. datalen       4    A dword indicating the number of bytes of voice data
  82.                     to be played. If the flag word is 0, then this number
  83.                     must not be greater than the length of the memory
  84.                     block.
  85. startpos      4    A dword indicating the offset within the memory block
  86.                     where playback is to begin. This value must be less
  87.                     than blocklen.
  88.  
  89. Return value        Meaning
  90. ------------        -------
  91.      0              success
  92.      1              data length greater than block size but no file read
  93.      2              block size is too small (datalength > blocksize and
  94.                      blocklen < 8192 and file read = yes)
  95.      3              unable to read from file
  96.      4              voice playback is already in progress
  97.      5              startpos is not less than blocklen
  98.  
  99.  
  100. ------------------------------------------------------------------------------
  101.  
  102. Catch-up routine
  103. ----------------
  104.  
  105. Declaration:
  106.  
  107. short pascal far PVOICE_CATCHUP(void)
  108.  
  109.  
  110. This must be called frequently from the main program if file reading is being
  111. used and the length of the data to be played is longer than the length of the
  112. memory block. The routine checks the progress of the address pointer in use
  113. by the interrupt service routine and fills in more data from the file if
  114. necessary.
  115.  
  116.  
  117. Return value        Meaning
  118. ------------        -------
  119.      0              success
  120.      1              error while reading file
  121.  
  122.  
  123. ------------------------------------------------------------------------------
  124.  
  125. Stop routine
  126. ------------
  127.  
  128. Declaration:
  129.  
  130. void pascal far PVOICE_STOP(void)
  131.  
  132.  
  133. Calling this will terminate the voice output operations immediately, before
  134. the end of output would have normally occurred. It is not necessary to call
  135. this routine unless it is desired to terminate voice output before the
  136. specified number of data bytes have been played.
  137.  
  138.  
  139. ------------------------------------------------------------------------------
  140.  
  141. Status routine
  142. --------------
  143.  
  144. Declaration:
  145.  
  146. short pascal far PVOICE_STATUS(pcount,pindex)
  147. long far *pcount;
  148. long far *pindex;
  149.  
  150.  
  151. This will report the status of voice operations, including whether the
  152. output operation has completed, whether all the necessary data has been
  153. read from the file, and the current count of data bytes played.
  154.  
  155.  
  156. The first parameter is a far pointer to a dword which will receive the number
  157. of bytes which have already been output to the speaker.
  158.  
  159. The second parameter is a far pointer to a dword which will receive the
  160. offset within the memory block of the next byte of data to be played.
  161.  
  162.  
  163. The return value is a flag word in which the lowest two bits are
  164. significant:
  165.  
  166. Bit #      Meaning if 1
  167. -----      ------------
  168.   0        playback is still in progress
  169.   1        unread data remains in file
  170.  
  171.  
  172.